Collection of Tools & Utilities/Collection of Tools and Utilities.iso/basic/vidbasic.zip/HELP.DOC

Text File | 1990-11-29 | 50KB | 977 lines

;Video routine short instruction list

========================================================================
    Copyright (C) Copr. 1990 by Sidney J. Kelly
            All Rights Reserved.
            Sidney J. Kelly
            150 Woodhaven Drive
            Pittsburgh, PA 15228
            home phone [phone] (7pm to 9:30pm EST)

     CompuServ   70043,1656
     Genie       S.KELLY8

========================================================================

          The following routines are designed to do something
useful to text without regard to the type of monitor actually
installed.  These routines are text mode primitives.  In most
cases that give you direct control over the hardware in a fashion
that cannot be done except in assembly language.  You can save
the display, write characters or attributes at high speed to the
display, or write to the display using DOS compatible modes to
allow you to use multi-taskers or ANSI.SYS.  You can change text
or attributes on the display.  You can adjust cursor size, turn
off blinking, BLOAD help files, etc.
          These routines are part of a larger freeware library of
QBASIC routines that is currently under construction.  The full
version will be released two days AFTER an OOPS version of QBASIC
is released by MICROSOFT-- at which time few will want to use
these routines.
          Why these were written:
          I originally wrote these routines to parrot Dick Evers
window routines written exclusively in BASIC (You can see his
influence in the demo program).  Then an old issue of PC Magazine
showed how to call MASM video routines from QBASIC, which I think
is based on an earlier BYTE magazine article.  Other PC Magazine
routines, and the discussions about IBM Technical reference video
adapter recognition routines, showed how to identify display
types using just BIOS calls.  Then the quest began: I began my
search of back issues of PC Magazine for programming tidbits, I
bought old assembly language guide books back with the earth was
fresh and the IBM PC with 64kb of memory and two floppies was a
wonder to behold, searched the standard databases for public
domain routines; read more programming books, etc.  The
bibliography at the end of this document should answer your
requests for additional information.
          The video display was selected for improvement because
that is one area a user can really notice the difference between
fast code and slow code.  Some of these routines allow you to do
things that are impossible otherwise.  Other routines allow you
to do something much faster and in an attractive fashion.  All
the routines avoid the agony of using ON ERROR GOTO traps.
          Programmers Assumptions:          These routines are designed to work with MONO, CGA,
HERC, MCGA (mostly color, though generally untested), EGA (mono
or color, 25 or 43 line mode), and VGA (mono or color, 25 or 50
line mode).  In a very limited way, the routines support dual
displays.  These routines assume that the display width is 80
columns wide, mostly because there is no known way to determine
in advance if a particular user's display will support 132 column
mode.  Anyway that is QBASIC's assumption too.  More importantly
I don't own a multi sync display, and I do not access to 10 types
of EGA and 50 types of VGA displays that are necessary to test
everything out on.  Finally, there are several shareware
libraries that already have some of the ATI, Paradise, VESA and
Video Seven EGA/VGA routines built in.  Unfortunately, after
looking at the freeware version of FRACINT (a nifty graphics time
waster that draws fractals), it appears that there are about five
or six different ways to switch displays into high resolution
mode.  Even FRACINT requires the user to select the display type.
(How can I convince my wife that I need a register compatible
8514/A display and adapter for the ultimate in text mode
displays??????????).
          It is possible to devote many hours to routines for
hardware 95% of the users wont have or need in text mode.  Most
of the direct screen routines use macros that are hard coded for
an 80 column width display. (Lengths of 25, 43, and 50 are
allowed).  This is done for speed in case the poor user only has
a CGA on a PC clone (he needs all the speed he can get).  To show
how it is done, I have included a few routines that actually do
use the BIOS ram data areas to determine the current display
width.
          QBASIC Theory.
          Aside from the current DEF SEG setting, most of QBASIC
video information storage registers are not available inside the
QB.EXE environment, though it is available inside the .EXE
program (which makes testing the routines way too time
consuming).  My routines had to come up with such information
independently.  My solution is store the key variables in the
default data segment in QBASIC (its name in MASM is DGROUP).  To
save space in DGROUP, only 7 bytes of information is kept by the
video routines.  This allows transparent sharing of the
information.  The reason for such "stupid" names (B$V...) for the
DGROUP variables is to only give the MASM routines access to such
information, and prevent normal QBASIC routines (or someone
else's library routines) from messing them up.
          Generally QBASIC only keeps simple variables, (INT,
LONGINT, SINGLE and DOUBLE, and STRINGS) in DGROUP.  Arrays and
TYPE records are usually kept outside DGROUP, with only the
STRING Descriptor or the undocumented Array descriptor kept in
DGROUP.  Thus, the library routines assume that all information
passed from simple variables is information about a near (DGROUP)
address.  If we pass simple integers to MASM routines, and don't
care to have MASM change those variables, we use BYVAL to send
the information to MASM.  If we want to have MASM send
information back about multiple variables, we pass the address
information for the variables without using BYVAL.  If we usearrays, we must use a combination of BYVAL and VARSEG and VARPTR
to get the information we need to manipulate the information
inside the arrays.  VARSEG and VARPTR are necessary because there
is a very great chance that the arrays will be stored as far data
(i.e. not stored in DGROUP).
          Text strings are sent by QBASIC as near address
(relative to DS and DGROUP).  The fist value in the descriptor is
the length of the string.  The second value is the offset address
inside DGROUP.  Fixed length strings are not referenced with
string descriptors.  For that reason, I don't allow such strings
as variables in my routines.
          QBASIC requires that MASM preserve BP, SI, DI, DS, and
keep the direction flag clear (CLD).  All these routines do this.
You will note that MICROSOFT'S CALL INTERRUPT routines do not
save BP (apparently to give you access to some EGA VGA palette
and character font selection routines in the BIOS), and thus will
crash if a critical error occurs.  MICROSOFT offers a replacement
routine, that overcomes this error by preventing any change to
BP.  You should get it if you don't already have it.
          The choice of defining MASM routines as SUB's or
FUNCTION's depends on whether you want to get information from
MASM in DX:AX (the format for FUNCTIONs), or if the MASM routine
either sends back no information or more than one variable (the
format for SUBs).  For simple one variable routines when MASM is
just returning a value, use FUNCTIONs.  To use such functions
inside QBASIC you must either assign the value of the function to
a QBASIC variable or use IF ... THEN statements (C style).  For
everything else use SUBS.
          Note due to an error in the QBASIC parser, always use
the CALL keyword to call the library routines if there is any
chance that you will use a colon as a separator on a line.
Without the CALL keyword, the QBASIC parser assumes that the
routine name followed by a colon is intended as a line label, and
not as a SUB name.  You must use CALL if you will use a SUB that
does not need any parameters and will